home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998…tember: Reference Library / Dev.CD Sep 98 RL2.toast / What's New / Software Development Kits / MacOS USB DDK / Mac OS USB DDK Readme < prev    next >
Encoding:
Text File  |  1998-07-20  |  18.5 KB  |  498 lines  |  [TEXT/ttxt]
  1.  
  2.  
  3.  
  4.  ***
  5.  ***       Universal Serial Bus(tm) (USB) for the Mac OS
  6.  ***    Mac OS USB 1.0 DDK Developer Release Notes
  7.  ***    Copyright 1998 Apple Computer, Inc.
  8.  ***
  9.  
  10.  
  11.  
  12.  Table of Contents:
  13. -------------------------------------------------------------
  14.  USB Fundamentals
  15.  Getting started with Mac OS USB
  16.  Installing the Mac OS USB Software
  17.  Using the Mac OS USB DDK under MPW
  18.  Installing the Mac OS USB DDK into MPW for the First Time  
  19.  Updating a Previously Installed USB DDK for MPW
  20.  Using the Mac OS USB DDK with MetroWerks CodeWarrior
  21.  Installing the Mac OS USB DDK for CodeWarrior for the First Time  
  22.  Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  23.  Using the CodeWarrior Project Files
  24.  Installing the Mac OS USB Components onto your Target System
  25.  Description of Installed Files
  26.  Known Problems
  27.  Contact Information
  28. -------------------------------------------------------------
  29.  
  30. USB Fundamentals
  31. ----------------
  32.  
  33. For the coming generation of Power Macintosh systems, USB is the 
  34. primary interface for connections to low to medium speed peripheral
  35. devices. There a numerous advantages for adopting the USB standard on
  36. Macintosh, and they are discussed in the "Mac OS USB DDK API Reference
  37. Guide". On the future Macintosh systems there will be no ADB, 
  38. Serial Port, or SCSI connections. USB will be the primary port 
  39. for connecting peripheral devices to the Macintosh. 
  40.  
  41. The DDK provides the tools, interfaces, system files, and module 
  42. examples for you to start development of USB products
  43. for the Macintosh. The DDK provides the same release of USB
  44. component software that ships on the introductory release of the
  45. Power Macintosh iMac system.
  46.  
  47. Getting started with Mac OS USB
  48. -----------------------------
  49.  
  50. As of the writing of this note, Power Macintosh Systems which have
  51. USB support built-in, are under development. Seed units for 
  52. Developers are limited and Apple will be unable to provide
  53. developments systems to all developers. To jump-start the 
  54. development process for Mac OS USB, you can obtain a PCI 
  55. USB card from three sources - ADS, OPTi and CMD Technology. 
  56. As other sources for PCI USB cards become available, 
  57. we will revise this readme to include them.
  58.  
  59. For OPTi, the web page is
  60.  
  61.         <http://www.opti.com/html/usbsolutions.html>.
  62.  
  63. For ADS, the web page is
  64.  
  65.   <http://www.adstechnologies.com/>
  66.  
  67. For CMD Technology, Inc, the web page is 
  68.  
  69.         <http://www.cmd.com/>.
  70.  
  71. We advise you to obtain cards from all sources so that you can
  72. test on all cards to ensure maximum compatibility.
  73.  
  74. With these cards, and the supplied software, you can start work on 
  75. developing your USB Modules to support your
  76. devices, along with the associated applications. The DDK provides 
  77. examples for both the MPW and MetroWerks CodeWarrior Pro
  78. environments. Please carefully, read the notes below, on how you 
  79. will need to configure your environment to build the example
  80. modules.
  81.  
  82.  
  83. Installing the Mac OS USB Software
  84. ---------------------------------
  85.  
  86. To install the USB System Software components, drag copy the 
  87. contents of the folder
  88.  
  89. :USBDDK:Extensions-AppleBuilt: 
  90.  
  91. to the Extensions folder, and reboot.
  92.  
  93.  
  94. Important Notes on Installation and Use of this Beta DDK software
  95. ------------------------------------------------------------
  96.  
  97. This DDK will let you look at the sources to some working class 
  98. drivers, build the examples, and develop & build your own code.
  99.  
  100. Please remember that these driver samples are Copyright Apple 
  101. Computer, Inc.. You may use the supplied code to develop Class 
  102. Drivers for your devices. As for publishing the source code, please
  103. check first with the Mac OS USB DDK License agreement, included
  104. in this DDK.
  105.  
  106. The current driver samples may, reflect the latest
  107. state of the art of driver writing for USB in the Mac OS. Note that
  108. the PrinterClassModule sample is for example
  109. purpose only. This sample is the basis for real
  110. drivers under development, however we are unable to provide
  111. the actual class driver code. The remaining examples are the
  112. real code for the Keyboard HID, Mouse HID, Universal HID, and 
  113. Composite class drivers which will ship on the iMac
  114.  
  115. While not extensively tested (by the development team), 
  116. the sample sources have been tweaked slightly to make builds 
  117. under CodeWarrior some what less problematic. The project files 
  118. are provided to help jumpstart your development process.
  119.  
  120.  
  121. Using the Mac OS USB DDK under MPW
  122. ---------------------------------
  123.  
  124. The following are guidelines for using this DDK with the 
  125. MPW programming environment.
  126.  
  127. 1. You must have MPW 3.4.2 (or later) from ETO 23. 
  128.  
  129.    We are not supporting the use of any versions of MPW
  130.    previous to v3.4.2.
  131.    
  132. 2. You must use the Universal Interfaces&Libraries 3.1 from the 
  133.    Apple ftp site. Follow the instructions which are provided
  134.    with the Interfaces&Libraries download to upgrade the 
  135.    MPW programming environment.  The URL for the Developer
  136.    Development Kits web page is
  137.    
  138.    <http://developer.apple.com/sdk/>
  139.    
  140. 3. You should update the USB.h file in the Universal Interfaces 
  141.    CIncludes folder with the USB.h file from the USBDDK 
  142.    Folder.
  143.           
  144. 4. Within MPW, there will be the USBDDK menu.  Choose
  145.    the desired sample module to build from the "Select Example"
  146.    menu item.  Use the "Build Driver or Example" menu item
  147.    to build the example file.  The driver modules which you 
  148.    build will be placed into the "USBDDK:Extensions-DDKBuilt:"
  149.    folder.
  150.  
  151.  
  152. Installing the Mac OS USB DDK into MPW for the First Time
  153. --------------------------------------------------------
  154.  
  155. 1. Drop the UserStartup•USBDDK into your MPW folder.  
  156.  
  157. 2. Ensure that the name of the development system's USB DDK
  158.    folder is USBDDK. The MPW scripts supplied in this DDK 
  159.    will fail if the folder is named differently.
  160.    
  161.    It has been reported that the USBDDK MPW startup script 
  162.    doesn't handle spaces that are part of the complete pathname
  163.    correctly. This should be corrected in a later release.
  164.  
  165. 3. Launch MPW
  166.  
  167.    You'll be prompted to point to  *YOUR* DDK folder.  That is, 
  168.    the USBDDK folder on your hard drive, not a projector 
  169.    database on a server.
  170.  
  171. 4. Drag the "Extensions-AppleBuilt" items into your "target" 
  172.    system's system folder, not the development system's system 
  173.    folder!  The development system only needs the contents of the
  174.    DDK and MPW folders.
  175.  
  176.  
  177. Updating a Previously Installed USB DDK for MPW
  178. ---------------------------------------------------
  179.  
  180. 0. Note the change of name for the DDK from NeptuneDDK to
  181.    USBDDK.
  182.  
  183. 1. Delete the file UserStartup•NeptuneDDK from your MPW folder.
  184.    If this file is left in, MPW will alert you to the fact
  185.    that it was unable to complete execution of a startup
  186.    command.
  187.  
  188. 2. Drop the UserStartup•USBDDK into your MPW folder.  This 
  189.    file may have changed from the last release of the DDK
  190.    
  191. 3. Drag *your* folders from inside the "Drivers" folder 
  192.    from the old DDK to the Driver folder of the new USB DDK 
  193.    folder. Make sure that the name of the folder is changed
  194.    to USBDDK
  195.    
  196. 4. Change the name of the *new* USB DDK folder to match 
  197.    *exactly* what your old USBDDK folder was called.
  198.    
  199. 5. If you don't get the name exactly right, then MPW will ask 
  200.    you to locate the folder the next time you start it.  
  201.    Be warned:  Spaces in the DDK folder name are NOT
  202.    recommended.
  203.    
  204. 6. Start MPW.  Any drivers you've moved from the old DDK to 
  205.    the new DDK's "Drivers" folder will automatically appear 
  206.    in the USBDDK Drivers submenu.
  207.  
  208.  
  209. Using the Mac OS USB DDK with MetroWerks CodeWarrior
  210. ---------------------------------------------------
  211.  
  212. We have supplied MetroWerks CodeWarrior project files for
  213. all of the USB Modules code examples. All of the project
  214. files were created using CodeWarrior Pro 1, IDE 2.0. The 
  215. project files are also compatible with CodeWarrior Pro IDE 
  216. 2.1 and 3.0.
  217.  
  218. For the CodeWarrior IDE environments v2.0 - v3.0, you must use
  219. the Universal Interface & Libraries v3.1. The examples will
  220. not build using the interfaces supplied with the CodeWarrior
  221. v.2 - v3.0 environments. The URL for the Developer Development
  222. Kits web page is
  223.    
  224.    <http://developer.apple.com/sdk/>
  225.  
  226. As mentioned for MPW, it is highly recommend that you use 
  227. one Macintosh for coding purposes and one Mac (aka "Target"
  228. system) for checkout/testing purposes.
  229.  
  230. The supplied project files will place the built drivers
  231. and extensions into the Target folder of the DDK.
  232.  
  233.  
  234. Installing the Mac OS USB DDK for CodeWArrior for the First Time
  235. -----------------------------------------------------------
  236.  
  237. 1. You can place the USBDDK anywhere on your development
  238.    system for the CodeWarrior environment. The access paths
  239.    for the project files are project and compiler relative.
  240.    If you move the examples folders out of the DDK, you must
  241.    fix the access paths so that the sources can be found.
  242.   
  243. 2. Ensure that the CodeWarrior IDE environment has the 
  244.    Universal Interfaces and Libraries 3.1 installed. The
  245.    download file from the DDK website includes instructions
  246.    for upgrading your CodeWarrior environment. Note that if
  247.    you upgrade your interfaces, you will also need to 
  248.    upgrade your precompiled headers. The supplied CodeWarrior
  249.    project files do not use precompiled headers.
  250.  
  251. 3. Copy the USB.h file included in this SDK to the 
  252.    ":Mac OS Support:Headers:Universal Headers:" folder.
  253.  
  254. 4. You will need to create a folder by the name
  255.  
  256.     "USBDDK:Extensions-MCWBuilt"
  257.  
  258.    This is the folder where the CodeWarrior projects will place 
  259.    the built examples. If this folder does not exist, or the folder 
  260.    name is named differently, the class driver samples will be
  261.    created in the CodeWarrior folder.
  262.  
  263. Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  264. -------------------------------------------------------------
  265.  
  266. 0. Note the change of name for the DDK from NeptuneDDK to
  267.    USBDDK.
  268.  
  269. 1. Copy the USB.h file included in this SDK to the 
  270.    ":Mac OS Support:Headers:Universal Headers:" folder. Do not
  271.    use the USB.h header file from an earlier USB DDK with the
  272.    supplied project files, as the examples may not build.
  273.  
  274. 2. If you experience compiler errors with the program samples,
  275.    check whether you have updated the USB.h header in the
  276.    ":Mac OS Support:Headers:Universal Headers:" folder.
  277.  
  278. 3. You will need to create a folder by the name
  279.  
  280.     "USBDDK:Extensions-MCWBuilt"
  281.  
  282.    This is the folder where the CodeWarrior projects will place 
  283.    the built examples. If this folder does not exist, or the folder 
  284.    name is named differently, the class driver samples will be
  285.    created in the CodeWarrior folder.
  286.  
  287. Using the CodeWarrior Project Files
  288. ---------------------------------
  289.  
  290.    For the following samples, there is only a single target for 
  291.    each project:
  292.  
  293.    CompositeClassDriver
  294.    KeyboardModule
  295.    MouseModule
  296.    UniversalModule
  297.  
  298.    For the PrinterClassDriver example, compile the targets in 
  299.    the following order
  300.  
  301.   1. PrinterClassDRVR - creates the 68K DRVR resource
  302.   2. PrintClassDriver - creates the USB PrintClassDriver module
  303.   3. ChooserPack.rsrc - creates the "PACK" resource
  304.   4. USB Chooser Driver - creates the Chooser extension for the 
  305.      USB printer
  306.  
  307. Installing the Mac OS USB Components onto your Target System
  308. -----------------------------------------------------------
  309.  
  310. IMPORTANT NOTE: Do not install the USB Extensions and Libraries
  311. into the System Folder of a CPU that has the USB Support integrated
  312. into the System ROM.
  313.  
  314. 1. Delete any existing files prefixed with "USB" from your system
  315.    folder's extension folder.  This applies only if an earlier 
  316.    pre-release version of Mac OS USB DDK software had been 
  317.    installed.
  318.  
  319. 2. Drag all the files from the 'USBDDK:Extensions-AppleBuilt' 
  320.    folder to the System Folder (ultimately destined for the 
  321.    system folder's extension folder). 
  322.  
  323. 3. Verify that all of the files that you dragged from the 
  324.    'Extensions-AppleBuilt' folder were placed in the system 
  325.    folder's extensions folder.
  326.    
  327.    
  328. Description of Installed Files
  329. --------------------------
  330. Files in the 'Extensions-AppleBuilt' folder:
  331. Files:                  Description:
  332. USBCompositeDriver      A class driver which is loaded for class 0 &
  333.                         and subclass 0 devices (typically keyboards &
  334.                         mice, although a few printers & modems appear 
  335.                         as composite class devices).
  336.                             
  337. USBFamilyExpert         The INIT (actually an 'expt') portion of the Family 
  338.                         Expert. Loaded prior to the INIT parade, it starts 
  339.                         the 'find a USB bus (i.e. UIM driver), loads the
  340.                         hub driver (for the root hub), and starts
  341.                         the hub driver running.  Once running, the
  342.                         hub driver locates devices attached to the
  343.                         port and asks the FamilyExpertLib to load
  344.                         drivers for the devices connected to the
  345.                         hub's ports.
  346.  
  347. USBHubDriver0 &         The Hub driver for the root hub, the Apple USB 
  348. USBHubDriver1           keyboard's hub, and some 3rd party hubs.
  349.  
  350. USBKeyboardModule       The HID Module loaded for a keyboard
  351.                         interface (typically in a compound device)
  352.                             
  353. USBMouseModule          A HID Module loaded for a mouse interface
  354.                         (typically in a compound device).
  355.                             
  356. USBHIDUniversalModule   A HID Module designed to support a number of 3rd
  357.                         party gaming devices via Game Sprockets.
  358.                         Refer to the "Mac OS USB Compatibility Notes"
  359.                         for a description of the game devices supported.
  360.                             
  361. USBOpenHCIDriver        The HAL (Hardware Abstraction Layer), also
  362.                         known as the "UIM" (USB Interface Module).
  363.                         This driver provides an abstracted interface
  364.                         to the OpenHCI host controllers on Mac
  365.                         motherboards and PCI controller cards.
  366.                             
  367. USBPrintDriver          A Printing Class Driver for experimentation
  368.                         purposes.  Printing WILL NOT be functional
  369.                         simply with the addition of this file.  The
  370.                         chooser extension needed for USB printing
  371.                         is still in development and has not yet
  372.                         been released.
  373.     
  374. Known Issues
  375. ------------
  376.  
  377. The following is a list of known issues with this final release
  378. of the USB DDK.
  379.  
  380.   - We are close to completing a document describing how to write
  381.     a USB driver. When this document is ready, we will place it on
  382.     the Mac OS USB web page at <usb.apple.com>.
  383.  
  384.   - The Mac OS USB DDK API Reference is close to final. This DDK
  385.     includes draft v13. When the document is final, a copy will be
  386.     placed on the Mac OS USB web page at <usb.apple.com>.
  387.  
  388.   - The Mac OS USB DDK v1.0 does not provide any isochronous
  389.     support. Isochronous support will be implemented in a 
  390.     future release of the Mac OS USB DDK.
  391.  
  392.   - For the USBBulkRead call, the buffer which you pass via the
  393.     usbBuffer field, must be aligned to a "MaxPacketSize" boundary. A
  394.     code snippet is provided in the USB Reference Guide to demonstrate
  395.     how to align a read buffer to a "MaxPacketSize" boundary. Note that
  396.     the buffer can be of any size, but preferably larger than 
  397.     "MaxPacketSize".
  398.  
  399.   - In the PrinterClassDriver sample, you may encounter a compiler
  400.     error while compiling the ChooserPack.rsrc target under CodeWarrior.
  401.     The "declaration syntax error" is reported in the "Chooser.h" file
  402.     regarding the use of the CFragConnectionID symbol. To fix this 
  403.     problem, add the statement
  404.  
  405.     #include <CodeFragments.h>
  406.  
  407.     to the list of included header files at the top of the header 
  408.     listing.
  409.  
  410.   - The USBGetPipeStatusByReference call does not function correctly. 
  411.     The pipe state is not returned in the state parameter. Instead 
  412.     one of these errors is returned:
  413.  
  414.     noErr                 specified pipe is active
  415.     kUSBPipeIdleError     specified pipe is in the idle state
  416.     kUSBPipeStalledError  specified pipe is stalled
  417.  
  418.     In a future release of USB, the USBGetPipeStatusByReference call will
  419.     correctly return the pipe state in the state parameter. Note that the
  420.                 kUSBUnknownPipeErr is a valid response for which the pipe state is
  421.     not returned.
  422.  
  423.   - The USBSetPipeIdleByReference call does not function correctly. The
  424.     following errors are returned, even though the call succeeded.
  425.  
  426.     kUSBIdleStalled    pipe was stalled, pipe is still idled despite error
  427.     kUSBPipeIdleError  pipe was already idle
  428.  
  429.   - The USBSetPipeActiveByReference call does not function correctly. The
  430.     following error is returned, even though the call succeeded.
  431.  
  432.     kUSBPipeIdleError  pipe was previously idle, pipe is still made active
  433.  
  434.   - The USBResetPipeByReference call does not function correctly. If 
  435.     kUSBPipeIdleError error is returned, the pipe may or may not have
  436.     been made active, depending on whether the pipe was previously stalled
  437.     or not. An idle pipe which was not stalled is not affected. An idle
  438.     pipe which was also stalled is made active. 
  439.  
  440.     This kUSBPipeStalledError error is also returned if the pipe was 
  441.     previously idle. The call has succeeded despite the error. 
  442.    
  443.  
  444. Contact Information
  445. -------------------
  446.  
  447.   Mac OS USB DDK Upgrades and latest information:
  448.     
  449.     Check the Developer Development Kits web page for
  450.         upgrades to the Mac OS USB DDK. The web page is
  451.         
  452.         <http://developer.apple.com/sdk/>
  453.  
  454.     For the latest information on Mac OS USB, check the Mac OS USB web page.
  455.     The web page is
  456.  
  457.     <http://usb.apple.com>
  458.  
  459.   For Bug Reports:
  460.  
  461.     To ensure the appropriate data is collected, please use the Bug Reporter  
  462.     to send us your bug reports. The Bug Reporter can be found at: 
  463.  
  464.     <http://developer.apple.com/bugreporter>
  465.  
  466.     When reporting problems, please include the machine configuration, 
  467.     including the vendor of the PCI USB card which you have tested with.
  468.  
  469.   For Technical Questions:
  470.  
  471.     Contact Worldwide Developer with purchased development-level technical 
  472.     support incidents at
  473.  
  474.     dts@apple.com
  475.  
  476.     Technical support incidents are bundled in our Premier and Select 
  477.     Developer programs. For information about joining our programs, 
  478.     please visit our Apple Developer Connection web site at 
  479.  
  480.     http://developer.apple.com/programs. 
  481.  
  482.     If you have never purchased a technical support incident and would like 
  483.     to find out how to do so, please visit the following site: 
  484.  
  485.     http://developer.apple.com/programs/techsupport.html . 
  486.  
  487.     
  488.   Comments, Suggestions and Enhancement Requests
  489.  
  490.     Please send all comments and suggestions regarding the Mac OS USB DDK to
  491.     
  492.     usb@apple.com
  493.  
  494.     All email sent to this address will be read, however, we will not be to
  495.     respond to all of your comments and suggestions.
  496.  
  497.         
  498.